Go 代码质量：格式、静态检查、测试和审查各管一段

“CI 全绿”可能只代表代码排得整齐，也可能代表编译、静态检查、业务测试都跑过。要让这句话有用，先把门禁拆清楚。本文用两个故意写坏的小程序看工具能抓什么、抓不到什么，再把人工审查放回合适的位置。

示例固定 Go 1.27.2、Linux/amd64。这里有一个与部分旧说明不同的实测结果：该版本的 go test 已经启用 slog 检查，帮助文字中的列表却仍漏写它。下文会把实际命令和对应源码放在一起，不用旧清单代替验证。

每个入口都应该有明确职责

入口	检查或修改什么	不能据此证明什么
gofmt	Go 源码的规范格式	业务规则正确、错误已处理
goimports	格式，以及增加缺失/移除未使用的 imports	替你选择了语义正确的架构依赖
go build	所选构建条件下能编译链接	测试通过、其他平台可运行
go vet	常见可疑写法，如复制锁、格式串、丢取消函数	所有错误都会被发现
Staticcheck	一组额外的静态分析规则	规则适合所有项目且没有误报
go test	实际编译并执行测试，还运行指定 vet 子集	所有输入与环境都覆盖
go test -race	本次运行中检测到的数据竞争	不存在逻辑竞态或未执行路径的竞争
Code Review	契约、设计、资源责任、可读性与遗漏	人工检查永远不会漏错

工具职责依据 gofmt、goimports、vet、Staticcheck、race。表中的限制是结合工具范围作出的判断，而不是声称任何工具都无用。

格式自动化，留下注意力讨论行为

附录的 badvet 程序故意挤在一起。执行 gofmt -d main.go，差异的一部分是：

-import("context";"sync";"time";"log/slog")
+import (
+    "context"
+    "log/slog"
+    "sync"
+    "time"
+)

这里为版面显示把差异中的 tab 展示为空格；原始输出保留真实 tab。gofmt 统一缩进、空格等排版，减少“这行应该几个空格”的审查争论。-d 看差异，-l 列出需要格式化的文件，-w 才会写回。gofmt 参数

本机 Go 1.27.2 的 gofmt -d 遇到差异退出 1，脚本显式接住这个结果，继续后面的教学实验。团队 CI 更常见的做法是检查 gofmt -l 是否输出文件名；别只看一次格式命令有没有打印文字，就默认语义检查也跑了。

goimports 还管理 imports，适合编辑器保存时使用；它增加的 import 仍值得看一眼，尤其是存在同名包或新依赖时。命令行可用 goimports -d . 查看差异，确认后用 goimports -w . 写回；这两条只是操作示意，本次未执行。本文只运行了 gofmt，没有安装和运行 goimports；引用固定 x/tools v0.35.0 文档是为了说明具体工具入口。goimports v0.35.0

编译能过，vet 仍能发现问题

badvet 的主体是：

var mu sync.Mutex
copied := mu
_ = copied
ctx, _ := context.WithTimeout(context.Background(), time.Second)
_ = ctx
slog.Info("created", "order_id")

go build 成功。显式运行 go vet ./... 得到四条诊断：

main.go:5:10: assignment copies lock value to copied: sync.Mutex
main.go:6:4: assignment copies lock value to _: sync.Mutex
main.go:7:6: the cancel function returned by context.WithTimeout should be called, not discarded, to avoid a context leak
main.go:9:2: call to slog.Info missing a final value

第一组检查复制含锁的值。这个例子复制的是未使用的零值锁，vet 仍会指出这种写法；不能把警告直接描述成“已经发生并发故障”。正确设计通常让含锁状态保留同一个实例，实际锁使用规则见 sync。

第二条提醒取消函数不能随手丢弃，通常应在对应作用域 defer cancel()，让超时计时器与子 context 尽早释放。context

最后一条指出日志参数落单。可以补成 "order_id", id，或者使用类型明确的 Attr；这属于可编译但很可能不是作者意图的代码。slog

go test 的 vet 子集：按版本查真实行为

本例不加额外参数执行 go test ./...，实际已经因 slog 缺值失败；它没有报告复制锁和丢取消函数。go test -x 中调用 vet 的参数包括：

-atomic -bools -buildtag -directive -errorsas -ifaceassert -nilfunc -printf -slog -stdversion -stringintconv -tests

Go 1.27.2 的 test.go 默认检查列表 也含 -slog。同一工具链的 go help test 文案仍未列出 slog，因此这里以固定版本实现和运行记录说明观察到的行为，不把文案清单当成完整事实。

实用结论很短：go test 不能替代显式的 go vet ./...；需要时 go test -vet=all 可以扩大测试时的检查集合。关闭 vet 应是诊断时有意识的临时动作，而不是为了让失败消失。go test 参数

静态分析看不懂你没有写出来的业务契约

第二个例子做百分比折扣：

func Apply(price, percent int) int { return price - percent }

go vet ./... 没有报告问题，但价格 200 打九折应是 180，回归测试得到：

discount_test.go:7: Apply(200,10)=190 want=180

工具无法从函数名猜出团队对金额单位、舍入与优惠的全部定义。测试将预期表达出来后，才有可执行的检查。真正修复还要确定整数金额、取整方向、百分比范围和溢出规则；把代码改成一行乘除并不自动解决所有金额问题。

Staticcheck 能在标准 vet 之外发现更多可疑写法，例如某些无效赋值、废弃 API 使用等；具体检查项和兼容的 Go 版本要查固定工具版本。golangci-lint 则把多种检查器组织到统一入口，增加的是管理能力，同时也带来规则配置和升级负担。Staticcheck 检查项、golangci-lint 配置

建议先启用有明确价值、团队知道如何修复的规则。新增一项规则时查看它报告什么、如何压制误报、对生成文件怎么处理；每个 suppress 注释应说明原因，避免把整包一并忽略。工具、配置和所用 Go 版本一起固定，升级作为可审查的变更，而非 CI 每次下载 latest。

依赖风险还可以用官方 govulncheck 检查已知漏洞及调用可达性。它依赖漏洞数据库和分析范围，不能保证“查不到就是安全”，也不替代凭据审查和输入校验。本文没有运行 Staticcheck、golangci-lint 或 govulncheck，不把文档能力写成项目已检查通过。Go 漏洞管理

三份风格资料该怎么用

资料	适合查什么	不能如何使用
Effective Go	命名、控制流、接口等传统 Go 写法	页面明确说它写于 2009 年，未覆盖所有新语言及生态变化，不能当作最新特性手册
Go Code Review Comments	常见审查意见，如错误、context、接口、goroutine 生命周期	不是语言语法定义，也不是每一条都机械适用
Uber Go Style Guide	一个成熟团队对可维护 Go 代码的具体约定	其组织级选择不是 Go 官方强制规范

来源：Effective Go 说明、Code Review Comments、Uber Guide。

例如“消费方定义小接口”能防止实现方提前暴露几十个方法；“避免可变全局状态”能让测试并发和依赖注入更清楚。但已有程序受兼容 API 约束时，改法需要结合迁移成本。两份指南的建议不一致时，先服从语言规则、正确性和项目既有约定，再记录团队为何选择某种风格，不用权威名称结束讨论。

Code Review 看工具留给人的问题

本文建议审查先沿调用链走一次，而非先挑命名。以下问题往往需要理解需求和生命周期：

• 输入非法时，错误是否传回恰当边界？是否把内部错误或凭据写进响应？
• 谁启动 goroutine，谁通知它结束，谁等待它退出？请求结束以后还会不会继续占资源？
• 锁保护哪组不变量？是否把外部调用放在锁内？返回的切片或 map 会不会暴露内部可变状态？
• 超时、连接、文件、响应体由谁释放？defer 所在的作用域是不是预期范围？
• 测试是否会在改错行为时失败，还是只执行了一遍代码？新增依赖是否值得后续维护成本？

这些检查对应 Go 审查惯例 和具体资源 API 契约，问题顺序属于本文建议。评论最好说明风险与一个可行方向，例如“这里返回的 map 与内部共享，调用方写入会绕过锁”，比“这里不优雅”更容易行动。

把门禁连成短而可解释的流程

正在绘制图示…

可切换适合窗口或原始尺寸

查看图源代码

flowchart LR
    E["编辑：gofmt / goimports"] --> B["编译与依赖一致性"]
    B --> V["vet / 选定静态规则"]
    V --> T["单元测试与必要 race"]
    T --> I["集成测试：真实边界"]
    I --> R["审查行为、风险与维护成本"]

放大图示

原始尺寸下可横向或纵向滚动；按 Escape 关闭。

正在绘制图示…

查看图源代码

flowchart LR
    E["编辑：gofmt / goimports"] --> B["编译与依赖一致性"]
    B --> V["vet / 选定静态规则"]
    V --> T["单元测试与必要 race"]
    T --> I["集成测试：真实边界"]
    I --> R["审查行为、风险与维护成本"]

箭头表示建议的反馈推进，不要求所有 CI job 串行等待。便宜检查尽早返回，昂贵测试可并行或分阶段；每一段都应明确失败含义。格式错误不必排队等数据库启动，发布分支也不能因为格式已过就跳过业务测试。

证据与复现边界

2026-10-13 实际执行 gofmt 差异检查、两个模块的 build/vet/test，并用 go test -x 核对 vet 参数。完整原始输出包含预期失败。关于 gofmt 退出码和 slog 默认检查的陈述限定到本次 Go 1.27.2；没有把检查器运行结果推成所有版本保证。

主要资料：cmd/gofmt、cmd/vet、Go 1.27.2 test.go、Effective Go、审查惯例、Uber Guide。

完整故意失败示例

保存以下文件，设置 GOTOOLCHAIN=local、GOFLAGS=-buildvcs=false，执行 bash run_quality.sh。这个实验保留错误是为了比较检查层次，不应复制到生产项目。若要进一步核对默认 vet 参数，在 quality/badvet 内执行 go test -x ./...；该命令应同样因 slog 缺值失败。

run_quality.sh

#!/usr/bin/env bash
set -eu
cd "$(dirname "$0")/quality/badvet"
echo '== formatting diff: no file changed =='
if gofmt -d main.go; then echo formatted=true; else echo needs_formatting=true; fi
echo '== compile passes =='
go build -o program .
echo '== default test vet subset =='
if go test ./...; then echo test_passed=true; else echo test_failed=true; fi
echo '== full vet: expected failure =='
if go vet ./...; then exit 1; else echo expected_failure=true; fi
cd ../badlogic
echo '== static checks accept the business bug =='
go vet ./...
echo '== regression test rejects it =='
if go test -count=1 ./...; then exit 1; else echo expected_failure=true; fi

quality/badlogic/discount.go

package discount

func Apply(price, percent int) int { return price - percent }

quality/badlogic/discount_test.go

package discount

import "testing"

func TestTenPercent(t *testing.T) {
	if got := Apply(200, 10); got != 180 {
		t.Fatalf("Apply(200,10)=%d want=180", got)
	}
}

quality/badlogic/go.mod

module example.com/v2/badlogic

go 1.27.2

quality/badvet/go.mod

module example.com/v2/badvet

go 1.27.2

quality/badvet/main.go

package main
import("context";"sync";"time";"log/slog")
func main(){
 var mu sync.Mutex
 copied:=mu
 _=copied
 ctx,_:=context.WithTimeout(context.Background(),time.Second)
 _=ctx
 slog.Info("created","order_id")
}